home *** CD-ROM | disk | FTP | other *** search
/ HPAVC / HPAVC CD-ROM.iso / BOI200P.ZIP / LIBRARY.DOC < prev    next >
Text File  |  1992-12-14  |  38KB  |  873 lines
  1. BOI 2.00 Procedure and Function Library  12/15/92
  2.  
  3.     BBS Onliner Interface 2.00 (Pascal)
  4.     (C) 1992 Andrew J. Mead
  5.     All Rights Reserved.
  6.  
  7.     Contact:
  8.     PO BOX 1155
  9.     Chapel Hill, NC 27514-1155
  10.     USA
  11.           or
  12.     1:3641/417 FidoNet   75:7919/417 DoorNet
  13.     #1@9952 WWIVnet      #1@9395 VirtualNet
  14.  
  15. Turbo Pascal and TP are registered trademarks of Borland International.
  16. Borland Pascal and BP are registered trademarks of Borland International.
  17.  
  18. This document contains two sections.  The first defines all public
  19. procedures and functions.  The second lists the private procedures and
  20. functions of each unit.
  21.  
  22. Sample entry:
  23.  
  24. Procedure DECLARATION                classification          UNIT
  25.     - argument listing (what this argument is)
  26.     This is what this procedure does.  This replaces this other Turbo
  27.     procedure.  A code sample for this procedure may follow.
  28.  
  29.  
  30. Public Procedures and Functions
  31.  
  32. Procedure ABORTGAME                  housekeeping            SUPPORT
  33.     - byte (minimum remote screen size in lines)
  34.     AbortGame is provided as a way to alert the remote user that their
  35.     screen does not appear to be large enough to use the door.  This
  36.     procedure will initiate the programs exit procedure chain.
  37.  
  38.  
  39. Procedure ASYNCINT : Interrupt       communications          ASYNC
  40.     AsyncInt is the internal asynchronious communications interrupt
  41.     handler.  This procedure should never, ever be called directly.
  42.     It is publicly declared because, for some reason, it doesn't seem
  43.     to work otherwise.
  44.  
  45.  
  46. Function CARRIER : boolean           communications          ASYNC
  47.     Carrier returns true if carrier is detected, the program is being
  48.     run in local mode, or the carrier detect override command line
  49.     switch was used.  This function is designed for internal BOI usage.
  50.     If you find your program needs to access it, I recommend writing
  51.     a shell procedure or function and placing it in IOLib.
  52.  
  53.  
  54. Procedure CHANGECOLOR                video                   IOLIB
  55.     - word (remote and local attributes)
  56.     ChangeColor allows you to set both remote and local text attributes
  57.     at once.  This procedure is usually used as a restore operation.
  58.     For general use you will probably want to use IOLib.PortBackground,
  59.     IOLib.PortColor, etc.  The passed argument contains the desired
  60.     remote text attribute as the low order byte, and the desired local
  61.     text attribute as the high order byte.
  62.     See IOLib.GetTextAttr for sample.
  63.  
  64.  
  65. Function CHARREADY : boolean         remote input            ASYNC
  66.     CharReady returns true if there are any characters waiting in the
  67.     communications input buffer.  This function is designed for
  68.     internal BOI usage only.  You should use IOLib.PortKeyPressed in
  69.     your programs.
  70.  
  71.  
  72. Procedure CHECKSECONDKEY             input                   IOSUPP
  73.     - var char (scan code to check/character to return)
  74.     CheckSecondKey is used to interpret extended character codes
  75.     returned by the local keyboard.  If the code is not processed, $00
  76.     is returned.  You could use this structure to implement more SysOp
  77.     functions such as ChatMode, etc...  This procedure is only called by
  78.     IOLib.ReadPortKey.  Here is a list of default function keys
  79.     key   function
  80.     [F2]  toggle boi_statmode (user status line display mode)
  81.     [F7]  decrease user's remaining time by one minute
  82.     [F8]  increase user's remaining time by one minute
  83.     [F9]  disconnect phone line and exit game with simulated line noise
  84.     [F10] exit game and return to BBS, notifying user of action
  85.  
  86.  
  87. Procedure CLEANSTRING                string                  IOLIB
  88.     - var string (string to process)
  89.     CleanString will remove all spaces from the beginning and end of a
  90.     string.  See IOLib.StripString for more complete processing.
  91.  
  92.         str := '  Test String  ';
  93.         SendString('***' + str + '***',false); {'***  Test String  ***'}
  94.         CleanString(str);
  95.         SendString('***' + str + '***',false); {'***Test String***'}
  96.  
  97.  
  98. Procedure CLEARBUFFERS               input                   IOLIB
  99.     ClearBuffers clears the input stream.  It removes all characters
  100.     the local keyboard input buffer and the remote communications input
  101.     buffer.  This procedure is helpful in limiting type ahead.
  102.  
  103.        SendString('Continue? [Y/N] ',false);
  104.        ClearBuffers;
  105.        repeat inchar := UpCase(ReadPortKey)
  106.        until inchar in ['Y','N'];
  107.  
  108.  
  109. Procedure CLEARINBUFFER              remote input            ASYNC
  110.     ClearInBuffer clears the communications input buffer, discarding any
  111.     characters waiting to be read.  This procedure is designed for
  112.     internal BOI usage only.  You should use IOLib.ClearBuffers in your
  113.     programs.
  114.  
  115.  
  116. Procedure CLRPORTSCR                 graphics                IOLIB
  117.     ClrPortScr clears the active display window on both local and
  118.     remote consoles.  This procedure replaces Crt.ClrScr.  If there is
  119.     a remote user, the user status line will be refreshed on the local
  120.     console.
  121.  
  122.  
  123. Procedure CLRPORTEOL                 graphics                IOLIB
  124.     ClrPortEOL blanks characters from the cursor to the right edge of
  125.     the screen.  This procedure replaces Crt.ClrEOL.
  126.  
  127.  
  128. Function DATHOF : pathstr            door information        DOORLIB
  129.     DatHOF returns the file name for the door's data Hall of Fame if the
  130.     door has a Hall of Fame.  This value can be changed by calling
  131.     DoorLib.DL_SetValue.
  132.  
  133.  
  134. Procedure DISPLAYTEXT                file handling           SUPPORT
  135.     - pathstr
  136.     DisplayText will display a formatted text file to the user.  This
  137.     procedural allows users to pause (spacebar) or exit (escape) at any
  138.     time during the display.  The formatting codes (as they stand now)
  139.     are thus:
  140.  
  141.     The first seven (7) characters of each line of a DisplayText text
  142.     file are reserved for formatting information.  Here is the header
  143.     layout: (Note: Windowing commands (W) don't follow the same format.)
  144.  
  145.     byte legal values  notes/meaning
  146.       1   + - C E B W  other values indicate comment, line is ignored
  147.       2     none       blank space
  148.       3     0..F       color value passed to PortBackground(color)
  149.       4     0..F       color value passed to PortColor(color,monochrome)
  150.       5     0..F       reserved
  151.       6     0..F       monochrome value passed to PortColor(color,mono)
  152.       7     none       blank space
  153.  
  154.     Any suggestions for extending the formatting codes, or fully
  155.     implementing the Windowing (W) directive are welcome.  When I add
  156.     language support, I'll be adding labels with a colon ":" in the
  157.     first column.
  158.  
  159.  
  160. Procedure DL_SETVALUE                door information        DOORLIB
  161.     - byte (index of value to change)
  162.     - pathstr (new value)
  163.     DL_SetValue allows the program (use extreme caution) to change
  164.     several door specific values.  These are the values that are
  165.     compiled into DoorLib through DOORLIB.DAT.
  166.     index  Function   value
  167.       1    InfoFile   File name of online instruction file
  168.       2    TxtHOF     File name of text Hall of Fame file
  169.       3    DatHOF     File name of data Hall of Fame file
  170.       4    LogFile    File name of door's error/activity log file
  171.       5    DoorName   Name by which the door refers to itself
  172.       6    Version    string representation of Door's version number
  173.  
  174.  
  175. Function DOORNAME : pathstr          door information        DOORLIB
  176.     DoorName returns the name that the door likes to call itself by.
  177.     This value can be changed by calling DoorLib.DL_SetValue.
  178.  
  179.  
  180. Procedure DOTIMEOUT                  internal housekeeping   IOLIB
  181.     - boolean (make noise indicator)
  182.     DoTimeOut is invoked if the remote user goes two minutes without
  183.     pressing the keyboard.  It is also called in some circumstances if
  184.     carrier is lost.  I do not recommend that your door call this
  185.     procedure.  DoTimeOut halts program execution and invokes the
  186.     exit procedure chain.
  187.  
  188.  
  189. Procedure DROPCARRIER                communications          ASYNC
  190.     DropCarrier will attempt to use DTR (Data Terminal Ready) to get
  191.     the modem to disconnect the phone.  This procedure should be used
  192.     with extreme prejudice.  This procedure should not be directly
  193.     called by your programs.  If this is necessary you should build a
  194.     shell procedure and place it in IOLib.
  195.  
  196.  
  197. Procedure ENDGAME                    hall of fame            SUPPORT
  198.     - string (user designation (i.e. Players, Traders, Users, etc...)
  199.     - boolean (score is valid of HOF consideration)
  200.     - boolean (score is cash instead of points)
  201.     - boolean (higher scores are better than lower scores)
  202.     EndGame is supplied as a sample Hall of Fame handling routine.  Most
  203.     of my games use this routine as is.  Star Traders uses a modified
  204.     one that uses the numeric type comp for scores as well as tracking
  205.     two seperate Hall of Fames.  This procedure will maintain a Hall of
  206.     Fame that contains the all time best score, the previous month's top
  207.     three scores, and the current month's top twenty.  It will also
  208.     create a text version of the Hall of Fame that details the all time
  209.     best score, last month's top three, and this month's top ten.  This
  210.     text Hall of Fame is ideal for one screen online bulletins.
  211.  
  212.  
  213. Function EXIST : boolean             file handling           IOLIB
  214.     - pathstr (file to look for)
  215.     Exist tells whether or not a file is actually present or not.  This
  216.     procedure should be used in conjunction with IOLib.Valid.
  217.  
  218.         if Valid(filename) then
  219.           begin
  220.             if Exist(filename) then
  221.                 DisplayText(filename)
  222.             else NotifySysOp(filename)
  223.           end
  224.         else { error handling }
  225.  
  226.  
  227. Procedure GETSTRING                  input                   IOLIB
  228.     - var string (input string)
  229.     GetString returns all characters input both locally and from remote
  230.     up to, but not including the next carriage return.  This effectively
  231.     replaces System.ReadLn for user input.
  232.     By utilizing the BOI system variable boi_nextchar, you can "push" a
  233.     character into this procedure.  This allows you to have one prompt
  234.     that allows both hot keys and string input.  See HiLo program for an
  235.     example of this technique.
  236.  
  237.  
  238. Procedure GETTEXTATTR                video                   IOLIB
  239.     - var word (remote and local text attributes)
  240.     GetTextAttr returns the current remote and local text attributes.
  241.     This is the BOI's replacement to Turbo Pascal's textattr variable.
  242.     The passed argument contains the desired remote text attribute as
  243.     the low order byte, and the desired local text attribute as the high
  244.     order byte.  This procedure is usually used in conjunction with
  245.     IOLib.ChangeColor to save then restore a given set of text
  246.     attributes.
  247.  
  248.         GetTextAttr(saveattribs);
  249.         {do something like write on user status line, changing color}
  250.         ChangeColor(saveattribs);
  251.  
  252.  
  253. Function GETTIMER : boolean          timing                  IOLIB
  254.     - var longint (base timer tick value)
  255.     - word (target number of seconds)
  256.     GetTimer returns true if val seconds have passed since the base
  257.     timer tick value was initialized (see IOLib.TimerSet).  These two
  258.     procedures can be used for benchmarking, user inactivity timing,
  259.     etc...
  260.  
  261.  
  262. Procedure GOTOPORTXY                 video                   IOLIB
  263.     - byte (x coordinate)
  264.     - byte (y coordinate)
  265.     GotoPortXY should be used instead of Turbo Pascal's GotoXY.
  266.  
  267.  
  268. Function HEX : byte                  miscellaneous           IOLIB
  269.     - char
  270.     Hex is used to convert hex character values "0".."9", "A".."F", and
  271.     "a".."f" into numeric values $0..$F.  This procedure is used most
  272.     notibly by Support.DisplayText when decoding formatting codes.
  273.  
  274.  
  275. Function INFOFILE : pathstr          door information        DOORLIB
  276.     InfoFile returns the name of the door's online instruction file.
  277.     This value can be changed by calling DoorLib.DL_SetValue.
  278.  
  279.  
  280. Function INTINIT : byte              communications          ASYNC
  281.     IntInit checks game configuration (foss_init) and attempts to
  282.     install either the FOSSIL or internal asynchronious communications
  283.     routines.  This Function returns zero (0) on success or thirty one
  284.     (31) on FOSSIL initialization failure.  It also installs the
  285.     housekeeping routines necessary to automatically disengage
  286.     communications when the program ends.  This function should not
  287.     be called under any circumstances by your program.  You should
  288.     let IOLib.SetPort call it.
  289.  
  290.  
  291. Function INTSTR : string             string                  IOLIB
  292.     - longint (integer value to convert to a string)
  293.     - byte (minimum size of string)
  294.     IntStr returns a string of an integer value.  Best utilized by
  295.     SendString for formatted (left or right justified) output.  IntStr
  296.     replaces the numeric output syntax found in Write and WriteLn.
  297.     Replace
  298.         WriteLn('Result: ',integervalue:6);
  299.     with
  300.         SendString('Result: ' + IntStr(integervalue,6),true);
  301.  
  302.  
  303. Function LEFTTIME : integer          timing                  IOLIB
  304.     LeftTime returns the users current time remaining in minutes.
  305.     LeftTime rounds down.  It returns -1 if time has expired.
  306.  
  307.  
  308. Procedure LINEWRITE                  formatted display       SUPPORT
  309.     - string (lstr : string;
  310.     - byte (color value to pass to PortColor(color,mono))
  311.     - byte (monochrome value to pass to PortColor(color,mono))
  312.     - boolean (indicate whether choice is currently valid)
  313.     LineWrite is designed to help create menu bars.  The colors passed
  314.     are for the text.  If the choice is valid, then the second character
  315.     in the string is highlighted (white).  The sample onliner HiLo
  316.     demonstrates this procedure better than I can here.  This procedure
  317.     is used by all of my online games.
  318.  
  319.  
  320. Function LOGFILE : pathstr           door information        DOORLIB
  321.     LogFile returns the name of the door's error (and soon to also be
  322.     activity) file.  This value can be changed by calling
  323.     DoorLib.DL_SetValue.
  324.  
  325.  
  326. Function MAX : word                  miscellaneous           IOLIB
  327.     - word
  328.     - word
  329.     Max returns the greater of two word values.
  330.  
  331.  
  332. Function MAXL : longint              miscellaneous           IOLIB
  333.     - longint
  334.     - longint
  335.     MaxL returns the greater of two longint values.
  336.  
  337.  
  338. Function MIN : word                  miscellaneous           IOLIB
  339.     - word
  340.     - word
  341.     Min returns the lesser of two word values.
  342.  
  343.  
  344. Function MINL : longint              miscellaneous           IOLIB
  345.     - longint
  346.     - longint
  347.     MilL returns the lesser of two longint values.
  348.  
  349.  
  350. Procedure NOTIFYSYSOP                file handling           IOLIB
  351.     - pathstr
  352.     NotifySysOp sends a message to the user that a given file can not be
  353.     located.  It asks the user to notify the SysOp so that the problem
  354.     can be fixed.  This is usually used in conjunction with IOLib.Exist.
  355.     See IOLib.Exist for sample.
  356.  
  357.  
  358. Function OPENFILE : word             file handling           IOLIB
  359.     - var file (file handle)
  360.     - word (record size)
  361.     - byte (file sharing mode)
  362.     - facctype (file access mode [reset/rewrite])
  363.     OpenFile is used to open non-text files.  Since it utilizes untyped
  364.     files, you'll need to use BlockRead and BlockWrite to access the
  365.     information in the file.  You need to give OpenFile a record size
  366.     (usually 1), a dos sharing mode (i.e. denynone+read_only), and
  367.     a file access mode (treset or trewrite).  OpenFile returns IOResult
  368.     from the last attempt to open the file.
  369.  
  370.         Assign(f,'roster.dat');
  371.         if Exist('roster.dat') then
  372.             OpenFile(r,SizeOf(rosterrec),denynone+read_only,treset);
  373.         BlockRead(r,rbuffer^,1,inread);
  374.  
  375.  
  376. Function OPENTEXT : word             file handling           IOLIB
  377.     - var text (file handle)
  378.     - byte (file sharing mode)
  379.     - facctype (file acces mode [reset/append/rewrite]
  380.     OpenText is the text file version of OpenFile.  There is no need to
  381.     specify record size, and there is the additional tappend file access
  382.     mode.  OpenText returns IOResult from the last attempt to open the
  383.     file.  See IOLib.OpenFile for sample.
  384.  
  385.  
  386. Function PADSTR : string             string                  IOLIB
  387.     - string (string to right justify)
  388.     - byte (minimum size of string)
  389.     PadStr returns a right justified version of the string it is sent.
  390.     PadStr is normally used with SendString to format output.  PadStr
  391.     replaces the formatting syntax of Write and WriteLn.
  392.     Replace
  393.         WriteLn(namestr:26);
  394.     with
  395.         SendString(PadStr(namestr,26),true);
  396.  
  397.  
  398. Procedure PORTBACKGROUND             video                   IOLIB
  399.     - byte (background color)
  400.     PortBackground replaces Turbo Pascal's TextBackground.  This
  401.     procedure will change color on both the local and remote screens.
  402.  
  403.  
  404. Procedure PORTCOLOR                  video                   IOLIB
  405.     - byte (foreground color / color modes)
  406.     - byte (foreground color / monochrome modes)
  407.     PortColor allows for color/monochrome screen control.  PortColor and
  408.     TextPortColor both replace Turbo Pascal's TextColor procedure.
  409.     PortColor allows you to program with different looks for both color
  410.     and monochrome modes.
  411.     Note: PortColor, TextPortColor, and PortBackground are all highly
  412.     optimized.  They depend heavily on the variables boi_r_textattr, and
  413.     boi_l_textattr.  If the BOI thinks that you are trying to change the
  414.     color to the color it thinks is set, these procedures will NOT do
  415.     anything.  The advantages are that it greatly speeds up remote
  416.     video, and it allows the programmer more freedom in style.  The one
  417.     caviat is that you must USE these procedures.  Be very careful about
  418.     imbedding color codes into your text stream.
  419.  
  420.  
  421. Procedure PORTCOLUMNONE              video                   IOLIB
  422.     PortColumnOne is the equivalent of Crt.GotoPortXY(1,WhereY).  It is
  423.     usually followed by a ClrPortEOL statement.
  424.  
  425.  
  426. Function PORTKEYPRESSED : boolean    input                   IOLIB
  427.     PortKeyPressed replaces Turbo Pascal's KeyPressed function.  If
  428.     there is a key waiting either in the local keyboard buffer or the
  429.     communications input buffer, this function will return true.
  430.  
  431.  
  432. Procedure PORTWINDOW                 video                   IOLIB
  433.     - byte (leftmost x coordinate of active window)
  434.     - byte (topmost y coordinate of active window)
  435.     - byte (rightmost x coordinate of active window)
  436.     - byte (bottommost y coordinate of active window)
  437.     PortWindow replaces TurboPascal's Window procedure.  When declaring
  438.     the entire screen, I recommend using the system variable
  439.     boi_pagelength to be the last variable passed.
  440.     You should be careful with your screen layout.  If your program will
  441.     requires a window that does not reach the right edge of the screen
  442.     that must be cleared at regular intervals, you need to be aware that
  443.     ANSI screen clearing will be tedious.  You'll need to clear each and
  444.     every square manually.  If, however, your window reaches the right
  445.     edge of the screen, clearing is much faster due to IOLib.ClrPortEOL.
  446.  
  447.  
  448. Function PROGRAMSET : boolean        door information        DOORLIB
  449.     - char (command line switch character to test for validity)
  450.     This procedure is used by GetCmBBS.GetCommand to test alternate
  451.     command line switch characters for validity.  This whole sequence
  452.     enables you to write doors that have some door specific command line
  453.     parameters.  My game Madness' -t Tournament Mode switch is one
  454.     example and Path Finder's -t Trail Mode is another.  I can think of
  455.     no reason for anything other than GetCommand to call ProgramSet.
  456.  
  457.  
  458. Procedure QUERYUSER                  video initialization    SUPPORT
  459.     - charset
  460.     QueryUser is used to prompt the player to tell what video graphics
  461.     mode they would like to use.  You send QueryUser a set of characters
  462.     that correspond the choices you wish to enable.
  463.         "Q" Quit now.  Halts the game
  464.         "1" ANSI color.
  465.         "2" ANSI monochrome.
  466.         "3" AVATAR/1 color.  (recommend checking boi_allowavt)
  467.         "4" AVATAR/1 monochrome.
  468.     If the game is being played locally, the following two modes are
  469.     also available.
  470.         "C" direct color.
  471.         "M" direct monochrome.
  472.     I recommend that you use this procedure before any other.  Many drop
  473.     files contain graphics information, but users are notorious for not
  474.     configuring their BBS account to what they actually have.  Back when
  475.     I used to log on at 1200 bps, I usually told the BBS that I did not
  476.     have ANSI capability because I did not want to sit through the ANSI
  477.     menus.  However, I was more than happy to play the ANSI games.
  478.  
  479.  
  480. Function READBUFFER : char           remote input            ASYNC
  481.     ReadBuffer returns the next character from the input buffer.  This
  482.     should only be called if Async.CharReady returns true.  If there is
  483.     no character waiting, and ReadBuffer is called, it will return #00.
  484.     This procedure should not be called directly by your program.  You
  485.     should use IOLib.ReadPortKey instead.
  486.  
  487.  
  488. Function READPORTKEY : char          input                   IOLIB
  489.     ReadPortKey returns the next waiting character from either the local
  490.     keyboard buffer or the port input buffer.  This function replaces
  491.     Turbo Pascal's ReadKey.  This behaves like ReadKey except that
  492.     extended codes (from the local keyboard) are not pushed into the
  493.     input buffer.  They are passed processed in the background by
  494.     IOSupp.CheckSecondKey.  ReadPortKey will wait until a character is
  495.     pressed.  You may want to use it in conjunction with PortKeypressed.
  496.     If this routine detects no remote activity for two minutes, it will
  497.     call IOLib.DoTimeOut and the program will terminate.
  498.  
  499.  
  500. Function REALSTR : string            string                  IOLIB
  501.     - real (real value to convert into a string)
  502.     - byte (minimum size of string)
  503.     - byte (number of digits to right of the decimal)
  504.     RealStr returns a right justified string version fo the real value
  505.     it is sent.  RealStr is normally used with SendString to format
  506.     output. RealStr replaced the formatting syntax of real values with
  507.     Write and WriteLn.
  508.     Replace
  509.         WriteLn(realnum:6:2);
  510.     with
  511.         SendString(RealStr(realnum,6,2),true);
  512.  
  513.  
  514. Procedure RESETPORTXY                video/positional        IOLIB
  515.     ResetPortXY restores the screen location of the cursor that was
  516.     saved by a call to IOLib.SetPortXY.  See SetPortXY for more info.
  517.  
  518.  
  519. Procedure SENDCHAR                   remote output           ASYNC
  520.     - char (character to send to remote)
  521.     SendChar sends a character to the communications port.  This
  522.     procedure should not be called directly.  You should use either
  523.     IOLib.SendString or IOLib.SendRemote instead.  If SendChar detects
  524.     that carrier has been lost, it will initiate the programs exit
  525.     procedure chain.
  526.  
  527.  
  528. Procedure SENDLOCAL                  internal output         IOLIB
  529.     - string (characters to output to local console)
  530.     SendLocal will send anything it is sent to the local console.  This
  531.     routine is meant for internal BOI use.  I recommend against calling
  532.     it from within your door.
  533.  
  534.  
  535. Procedure SENDREMOTE                 internal output         IOLIB
  536.     - string (characters to send to remote console)
  537.     SendRemote will send anything it is sent to the remote console. This
  538.     routine is meant for internal BOI use.  I recommend against calling
  539.     it from within your door.  If you wish to supress local console
  540.     echoing, set the variable boi_echo to false and use SendString.
  541.  
  542.  
  543. Procedure SENDSTRING                 output                  IOLIB
  544.     - string (string to output)
  545.     - boolean (send a carriage return/linefeed indicator)
  546.     SendString replaces Turbo Pascal's Write and WriteLn output
  547.     procedures (for consoles).  This is the main output procedure.
  548.     For formatting output see IntStr, PadStr, and RealStr.
  549.  
  550.  
  551. Procedure SETBUFFERSIZE              remote input            ASYNC
  552.     - integer (new circular input buffer size [2..1024])
  553.     SetBufferSize allows you to change the remote "type ahead" buffer.
  554.     A call to SetBufferSize will also erase anything currently in the
  555.     input buffer.  SetBufferSize will accept values from 2 to 1024
  556.     (default).  I recommend against any calls to this procedure.
  557.  
  558.  
  559. Procedure SETLOCALGRAPHMODE          video                   IOLIB
  560.     - boi_grmode (new graphics mode [ASCII,ANSI,AVATAR,CRT]
  561.     SetLocalGraphMode should be used to change the local graphics mode.
  562.     When switching graphics modes, certain values need to be
  563.     initialized.  This procedure will take care of the housekeeping.
  564.  
  565.  
  566. Function SETPORT : byte;             communications          IOLIB
  567.     SetPort initializes BOI communications.  This function should be
  568.     used to access the communications routines in Async.  This function
  569.     is called by GetCmBBS.GetCommand.  On the first call to SetPort,
  570.     SetPort calls Async.IntInit and returns the value that IntInit
  571.     returns to it.  On subsequent calls, SetPort does nothing but
  572.     return $FF (255).
  573.  
  574.  
  575. Procedure SETPORTXY                  video/positional        IOLIB
  576.     SetPortXY and ResetPortXY are used in tandem to save a given cursor
  577.     postition then restore it later.  Use of this pair should replace
  578.     the local programming paradigm of calling WhereX and WhereY, saving
  579.     the temp values, then using GotoXY to move around.  In a future
  580.     version of the BOI, I may try to track remote screen position.
  581.  
  582.  
  583. Procedure SETTEXTATTR                internal video          IOLIB
  584.     - word (attributes to set)
  585.     SetTextAttr is provided merely as a complement to GetTextAttr and
  586.     ChangeColor.  This procedure allows you to tell the BOI that the
  587.     text attributes are something other than what the BOI thinks they
  588.     are.  If you need to use this procedure, I recommend that you
  589.     reconsider your programming techniques.
  590.  
  591.  
  592. Procedure STRIPSTRING                string                  IOLIB
  593.     - var string (string to process)
  594.     - charset (set of characters to remove from string)
  595.     StripString is provided as a simple way to remove unwantedd
  596.     characters from a string.  This is more comprehensive than the
  597.     procedure CleanString.
  598.  
  599.         str := '  Test String  ';
  600.         SendString('***' + str + '***',false);  "***  Test String  ***"
  601.         StripString(str);
  602.         SendString('***' + str + '***',false);  "***TestString***"
  603.  
  604.  
  605. Procedure TEXTPORTCOLOR              video                   IOLIB
  606.     - byte (color to set following text to)
  607.     TextPortColor and PortColor both replace Turbo Pascal's TextColor
  608.     procedure.  This procedure is a direct replacement.  If you want
  609.     to take color/monochrome modes into account, see PortColor.
  610.  
  611.  
  612. Procedure TIMERSET                   timing                  IOLIB
  613.     - var longint (base initialized value)
  614.     TimerSet initializes basetime to the current timer tick value.  This
  615.     value can then be sent to GetTimer as a test to see if a certain
  616.     number of timer ticks (18.2 per second) have elapsed.
  617.  
  618.  
  619. Function TXTHOF : pathstr            door information        DOORLIB
  620.     TxtHOF returns the file name for the door's text Hall of Fame if the
  621.     door has a Hall of Fame.  This value can be changed by calling
  622.     DoorLib.DL_SetValue.  Be careful changing this.  Changing this can
  623.     interfere with the BOI's /Y command line parameter.  Support.EndGame
  624.     uses the system variable boi_texthof that contains a complete path
  625.     and file name (from GetCmBBS.GetCommand).
  626.  
  627.  
  628. Procedure UPDATESTATLINE             sysop                   IOLIB
  629.     If there is a remote user, calls to UpdateStatLine will refresh
  630.     the User Status Line.  The displayed line information can be
  631.     toggled by the SysOp pressing [F2].  The display mode can also be
  632.     changed directly by setting boi_statmode.  UpdateStatLine also
  633.     maintains a timer value of the last time it was called, boi_smtime,
  634.     so that you can space out calls to the status line.
  635.  
  636.  
  637. Function VALID : boolean             file handling           IOLIB
  638.     - pathstr (filespec to verify)
  639.     Valid tells whether or not a given path/filespec is a valid DOS
  640.     filename.  This function should be used before attempting to open
  641.     any user named files.  See IOLib.Exist for more.
  642.  
  643.  
  644. Function VERSION : pathstr           door information        DOORLIB
  645.     Version returns the door's current version number.  This value can
  646.     be changed by calling DoorLib.DL_SetValue.
  647.  
  648.  
  649. Function WRITECOPY : boolean         housekeeping            SUPPORT
  650.     - boolean (do we ask if they want instructions?)
  651.     WriteCopy is the door and interface's copyright notice screen.  It
  652.     also indicates to the player whether or not the game has been
  653.     registered.  You can have WriteCopy prompt the player to indicate
  654.     if they wish to read the online instructions.  WriteCopy will
  655.     return true if they do.  All of my doors call this immediately
  656.     after calling Support.QueryUser.
  657.  
  658. -----
  659. Unit Async Internals
  660.  
  661. Function IntInit                     public procedure        ASYNC
  662.  
  663.   Procedure ASYNCINIT                communications          ASYNC
  664.       AsyncInit is called by IntInit if the internal communication
  665.       routines are used.  AsyncInit installs and activates the
  666.       interrupt handler Async.AsyncInt.  It als inserts Async.AsyncEnd
  667.       into the exit procedure chain.
  668.  
  669.   Procedure FOSSILINIT               communications          ASYNC
  670.       FOSSILInit is called by IntInit if FOSSIL communications routines
  671.       are used.  FOSSILInit initialized the FOSSIL and inserts
  672.       Async.FOSSILEnd into the exit procedure chain
  673.  
  674. Procedure ASYNCEND                   exit procedure          ASYNC
  675.     AsyncEnd, which is installed by Async.IntInit.AsyncInit, restores
  676.     the communication interrupt handler to its original state.
  677.  
  678. Procedure FOSSILEND                  exit procedure          ASYNC
  679.     FOSSILEnd, which is installed by Async.IntInit.FOSSILInit,
  680.     deinitializes the FOSSIL driver.
  681.  
  682.  
  683. -----
  684. Unit BOIDecl Internals
  685.  
  686. Procedure CALLOLDINT                 interrupt handling      BOIDECL
  687.     CallOldInt allows BOIInt08h to chain to the previous timer
  688.     interrupt.
  689.  
  690. Procedure BOIINT08H interrupt        interrupt handler       BOIDECL
  691.     BOIInt08h is the BOI's timer ISR.
  692.  
  693. Procedure NULLPROC                   empty procedure         BOIDECL
  694.  
  695. Procedure DV_WAIT                    timing                  BOIDECL
  696.     Used to give time slices back to DESQview.
  697.  
  698. Procedure DV_CRIT                    interrupt handling      BOIDECL
  699.     Used to tell DESQview not to switch away.
  700.  
  701. Procedure DV_SAFE                    interrupt handling      BOIDECL
  702.     Used to let DESQview know that it is safe to switch away.
  703.  
  704. Function CHECKDV : boolean           initialization          BOIDECL
  705.     Used to determine if DESQview is present, and, if so, initialize
  706.     certain BOI system values.
  707.  
  708. Procedure MS_WAIT                    timing                  BOIDECL
  709.     Used to give time slices back to MS Windows.
  710.  
  711. Procedure WIN_CRIT                   interrupt handling      BOIDECL
  712.     Used to tell MS Windows not to switch away.
  713.  
  714. Procedure WIN_SAFE                   interrupt handling      BOIDECL
  715.     Used to let MS Windows know that it safe to switch away.
  716.  
  717. Function CHECKWINDOZE : boolean      initialization          BOIDECL
  718.     Used to determine if MS Windows is present, and, if so, initialize
  719.     certain BOI system values.
  720.  
  721. Procedure DOS_IDLE                   timing                  BOIDECL
  722.     Used to give time back to other processes.
  723.  
  724. Procedure CHECKDOSVERS               initialization          BOIDECL
  725.     Used to determine what DOS, OS/2 DOSbox version is present and to
  726.     initialize certain BOI system values.
  727.  
  728. Procedure SETINDOS                   initialization          BOIDECL
  729.     Used to set the InDOS flag pointer.  This allows processes to
  730.     determine when DOS is re-entrant.
  731.  
  732. Procedure BOIEXIT                    exit procedure          BOIDECL
  733.     BOIDecl exit procedure.
  734.  
  735. Unit BOIDECL                         initialization          BOIDECL
  736.  
  737.  
  738. -----
  739. Unit DoorLib Internals
  740.  
  741. Procedure CHECKENVIRONMENT           initialization          DOORLIB
  742.     Used to look for BOILOG environment variable, which is not presently
  743.     documented.  It is present in anticipation of the expanded activity
  744.     logging of the next public release.
  745.  
  746. Unit DOORLIB                         initialization          DOORLIB
  747.  
  748.  
  749. -----
  750. Unit GetCmBBS Internals
  751.  
  752. Procedure GETCOMMAND                 initialization          GETCMBBS
  753.      Reads and process the command line parameters.  Reads and processes
  754.      the BBS drop file.
  755.  
  756.   Procedure SHOWERROR                error handling          GETCMBBS
  757.        Displays initialization error.
  758.  
  759.     Procedure WRITEERROR             error handling          GETCMBBS
  760.          Used to format display of ShowError.
  761.  
  762.   Procedure SETGAMETIME              timing                  GETCMBBS
  763.        Used to normalize user's time remaining.
  764.  
  765.   Procedure FINDDROPFILE             file handling           GETCMBBS
  766.        Used to locate BBS drop file.
  767.  
  768.   Procedure PROCESSTEXT              file handling           GETCMBBS
  769.        Used to process BBS drop files in text format (CRLF delimited).
  770.  
  771.     Procedure RESTART                file handling           GETCMBBS
  772.          Used to retrieve a specified line from drop file.
  773.  
  774.     Procedure DORBBS                 drop file processing    GETCMBBS
  775.          Used to obtain additional information from RBBS dropfile.
  776.  
  777.     Procedure DOWWIV                 drop file processing    GETCMBBS
  778.          Used to obtain additional information from WWIV dropfile.
  779.  
  780.     Procedure DOSPITFIRE             drop file processing    GETCMBBS
  781.          Used to obtain additional information from Spitfire dropfile.
  782.  
  783.     Procedure DOWILDCAT              drop file processing    GETCMBBS
  784.          Used to obtain additional information from WildCat! dropfile.
  785.  
  786.     Procedure DO2AM                  drop file processing    GETCMBBS
  787.          Used to obtain additional information from 2 A.M. dropfile.
  788.  
  789.     Procedure DOPHOENIX              drop file processing    GETCMBBS
  790.          Used to obtain additional information from Phoenix dropfile.
  791.  
  792.   Procedure PROCESSFILE              file handling           GETCMBBS
  793.        Used to process BBS drop files in binary format.
  794.  
  795.     Procedure DOOPUS114              drop file processing    GETCMBBS
  796.          Used to obtain additional information from Opus 1.14 dropfile.
  797.  
  798.   Procedure DOPCBOARD12              drop file processing    GETCMBBS
  799.        Used to process PCBoard 12.x format drop files.
  800.  
  801.   Procedure DOSEARCHLIGHT            initialization          GETCMBBS
  802.        Used to notify BOI that BBS is passing all arguments via command
  803.        line.
  804.  
  805.   Procedure GETCOMPORT               communications          GETCMBBS
  806.        Used to process user specified com port.
  807.  
  808.   Procedure GETIRQINFO               communications          GETCMBBS
  809.        Used to process user specified IRQ/port address.
  810.  
  811.   Procedure GETHOFLIM                hall of fame            GETCMBBS
  812.        Used to process Hall of Fame limiting value.
  813.  
  814.   Procedure GETHOF                   hall of fame            GETCMBBS
  815.        Used to process new text Hall of Fame path/filespec
  816.  
  817.   Procedure GETTIMELIMIT             timing                  GETCMBBS
  818.        Used to process absolute maximum time limit.
  819.  
  820.   Procedure DOPORTS                  communications          GETCMBBS
  821.        Used to normalize com port values.
  822.  
  823.   Procedure GETAGAIN                 timing                  GETCMBBS
  824.        Used to process replay time value.
  825.  
  826.   Procedure GETNAME                  user information        GETCMBBS
  827.        Used to process user's name.
  828.  
  829. Procedure GCEXIT                     exit procedure          GETCMBBS
  830.     GetCmBBS exit procedure.
  831.  
  832. Unit GETCMBBS                        initialization          GETCMBBS
  833.  
  834.  
  835. -----
  836. Unit IOLib Internals
  837.  
  838. Function AVSTR : string              output                  IOLIB
  839.     AVATAR/1 string generator
  840.  
  841. Procedure IOEXIT                     exit procedure          IOLIB
  842.     IOLib exit procedure.
  843.  
  844. Unit IOLIB                           initialization          IOLIB
  845.  
  846.  
  847. -----
  848. Unit Key Internals
  849.  
  850. Procedure GETREG                     registration            KEY
  851.     Registration key processor.
  852.  
  853. Unit KEY                             initialization          KEY
  854.  
  855.  
  856. -----
  857. Unit Support Internals
  858.  
  859. Procedure QueryUser                  public procedure        SUPPORT
  860.  
  861.   Procedure QUERYCHOICE              initialization          SUPPORT
  862.  
  863.   Procedure SETVALUES                initialization          SUPPORT
  864.  
  865. Procedure EndGame                    public procedure        SUPPORT
  866.  
  867.   Function HOFCHECK : boolean        hall of fame            SUPPORT
  868.  
  869.   Function GOODSCORE : boolean       hall of fame            SUPPORT
  870.  
  871.   Function BETTERSCORE : boolean     hall of fame            SUPPORT
  872.  
  873. END BOI Procedure and Function Library